home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / emsif24a.zip / EMSIF.DOC next >
Text File  |  1993-06-27  |  58KB  |  1,259 lines
  1.                                  EMSIF
  2.           Version-independent C Interface to LIM EMS Functions
  3.                   for LIM EMS versions 3.0 and higher
  4.                            EMSIF version 2.4
  5.                           by James W. Birdsall
  6.                                 06/27/93
  7.  
  8.  
  9. 0. CONTENTS
  10. -----------
  11.  
  12.    0.     CONTENTS
  13.    I.     INTRODUCTION
  14.     I.1    WHAT IS SUPPORTED
  15.     I.2    COPYRIGHT, LICENSE, AND WARRANTY DISCLAIMER
  16.    II.    USING EMSIF
  17.     II.1   COMPILING AND LINKING WITH THE LIBRARIES
  18.     II.2   EMSTEST, THE EXAMPLE PROGRAM
  19.    III.   PROGRAMMING WITH EMSIF
  20.     III.1  INITIALIZING THE LIBRARY
  21.     III.2  ORDINARY USE
  22.     III.3  FRAME CACHING AND ALIASING
  23.     III.4  SAVE/RESTORE
  24.     III.5  OTHER TIPS
  25.     III.6  FUNCTION GROUPING
  26.    IV.    LIBRARY REFERENCE
  27.     IV.1   GLOBAL VARIABLES
  28.     IV.2   FUNCTIONS
  29.    V.     ERROR CODES
  30.     V.1    INTERNAL ERRORS
  31.     V.2    EMS DRIVER ERRORS
  32.    VI.    THE END
  33.     VI.1   ACKNOWLEDGEMENTS
  34.     VI.2   TRADEMARKS
  35.  
  36.  
  37. I. INTRODUCTION
  38. ---------------
  39.  
  40.    EMSIF provides a high-level interface to LIM EMS control functions
  41. for common operations such as allocating, mapping, and freeing EMS, and
  42. copying data to and from EMS. The interface has been made independent of
  43. the EMS version implemented by the EMS driver as far as possible, so
  44. that parameters and returned data are always in the same format, but the
  45. EMS call most appropriate to the EMS version implemented by the driver
  46. is used.
  47.  
  48.    EMSIF is written in assembly language for speed and compactness and
  49. assembled with Borland's Turbo Assembler (TASM) 2.5. The source code is
  50. not compatible with the Microsoft Assembler (MASM).
  51.  
  52.  I.1 WHAT IS SUPPORTED
  53.  ---------------------
  54.  
  55.    EMSIF expressly supports the Lotus-Intel-Microsoft (LIM) Expanded
  56. Memory Specification (EMS) versions 3.0, 3.2, and 4.0. Versions above
  57. 4.0 are supported as 4.0. Versions below 3.0 are not supported.
  58. Save/restore is not supported under version 3.0, and assigning names to
  59. EMS handles and unmapping logical pages are only supported under version
  60. 4.0. These exceptions to version-independence are due to limitations of
  61. the unsupported versions; the necessary services are not available from
  62. the driver.
  63.  
  64.    EMSIF supports tiny, small, medium, compact, large, and huge memory
  65. models. The small model library supports both tiny and small models, so
  66. no library is provided specifically for tiny model.
  67.  
  68.    EMSIF supports any version of Turbo C, Turbo C++, or Borland C++, in
  69. both C and C++ modes, and Microsoft C 6.00 and above. This version of
  70. EMSIF has been tested with Borland C++ 2.0, Turbo C 2.0, Microsoft C 7.0
  71. and 8.0 (in Microsoft Visual C++ 1.0) in all of the supported memory
  72. models. EMSIF should work with earlier versions of Microsoft C and any
  73. other C compiler that 1) uses compatible parameter passing and return
  74. methods and 2) can use standard-format libraries.
  75.  
  76.  I.2 COPYRIGHT, LICENSE, AND WARRANTY DISCLAIMER
  77.  -----------------------------------------------
  78.  
  79.    EMSIF is not in the public domain. All the files are copyright 1991,
  80. 1992, 1993 by James W. Birdsall, all rights reserved. Permission is
  81. granted to do the following:
  82.  
  83.         You may freely redistribute this archive, so long as it contains
  84.         all the files listed in the file MANIFEST, intact and
  85.         unmodified.
  86.  
  87.         You may use the libraries in programs for your own use. You may
  88.         not distribute programs linked with these libraries.
  89.  
  90.    Payment of the $5 shareware registration fee ($50 for commercial use)
  91. grants the following license, in addition to the permissions listed
  92. above:
  93.  
  94.         You may request the source to EMSIF. You may modify the source
  95.         as necessary for use in your programs. However, you may not
  96.         redistribute either the original or modified source.
  97.  
  98.         You may distribute programs linked with either the original
  99.         libraries or libraries generated from source you have modified,
  100.         without royalty, provided you (a) do not alter or remove
  101.         copyright notices contained therein and (b) you indemnify, hold
  102.         harmless, and defend the author from and against any claims or
  103.         lawsuits, including attorney's fees, that arise or result from
  104.         the use or distribution of your software product. 
  105.  
  106. For the purposes of this license, commercial use is defined as use by an
  107. incorporated entity in a software product that is regarded as the
  108. product of the corporation, no matter how the software product is
  109. distributed, but only if 100 or more copies of the product are expected
  110. to be made.
  111.  
  112.    The contents of the distribution archive, and all other related
  113. files, information, and services are provided "as is" and without
  114. warranty. To the extent permitted by applicable law, the author
  115. disclaims all warranties, express or implied, including but not limited
  116. to, any implied warranty of merchantability or fitness for a particular
  117. purpose. While effort has been made to ensure that the files, information,
  118. and services are accurate and correct, the author shall not be liable
  119. for damages arising out of the use of or inability to use this product,
  120. including but not limited to, loss of profit, data, or use of this
  121. software, or special, incidental, or consequential damages or other
  122. similar claims, even if the author has been specifically advised of the
  123. possibility of such damages. Some states do not allow the exclusion of
  124. incidental or consequential damages, so the foregoing limitation may not
  125. apply to you.
  126.  
  127.    Information on contacting the author is provided at the end of this
  128. file.
  129.  
  130.  
  131. II. USING EMSIF
  132. ---------------
  133.  
  134.    This section describes how to use the EMSIF libraries with your
  135. programs.
  136.  
  137.  II.1 COMPILING AND LINKING WITH THE LIBRARIES
  138.  ---------------------------------------------
  139.  
  140.    EMSIF is provided as Borland/Microsoft standard library files.
  141. Libraries are provided for small, medium, compact, large, and huge
  142. memory models (tiny model uses the small model library). The model for
  143. which a library is intended is indicated by the last letter of the
  144. filename proper, which is the same as the first letter for the model.
  145. For example, EMSIFL.LIB is the large model library.
  146.  
  147.    To use EMSIF, you must #include the file EMSIF.H in every source file
  148. that calls EMSIF functions, accesses EMSIF global variables, or uses
  149. #defined constants provided by EMSIF. The same EMSIF.H file supports
  150. both C and C++.
  151.  
  152.    The procedures for linking EMSIF with the rest of your program vary
  153. according to the compiler and method you are using. In general, you must
  154. include the appropriate library (the library corresponding to the memory
  155. model in which you have compiled the rest of your program) in the link.
  156.  
  157.    If you are compiling in the Integrated Development Environment of
  158. Turbo/Borland C[++] or Microsoft Visual C++, include the name of the
  159. appropriate library in the project file for your program. For example,
  160. if you are working in the compact memory model, include EMSIFC.LIB in
  161. your project file.
  162.  
  163.    If you are using a command-line compiler (bcc, tcc, or cl) to compile
  164. and link, simply place the full name of the appropriate EMSIF library on
  165. the command line. For example, "bcc -mc foo.c emsifc.lib" will compile
  166. the file "foo.c" in the compact model and link it with emsifc.lib.
  167.  
  168.    If you are linking manually (using TLINK or LINK), place the name of
  169. the appropriate library in with the other libraries. For example,
  170.         tlink c0c.obj foo.obj, foo.exe, foo.map, cc.lib emsifc.lib
  171. or
  172.         link foo.obj, foo.exe, foo.map, emsifc.lib ;
  173. will link the object "foo.obj" with the appropriate startup object and
  174. standard library (LINK automatically includes the startup object and
  175. standard library, so it is not necessary to explicitly include them) and
  176. the compact model EMSIF library.
  177.  
  178.  II.2 EMSTEST, THE EXAMPLE PROGRAM
  179.  ---------------------------------
  180.  
  181.    A large and complete example program and tester, EMSTEST, has been
  182. included in this distribution. It can be compiled in any of the
  183. supported memory models (although ti